Skip to content

refactor: share file handling and the REST contract through pivotkit-node - #736

Merged
eizedev merged 2 commits into
mainfrom
refactor/shared-node-package
Nov 22, 2026
Merged

eizedev merged 2 commits into
mainfrom
refactor/shared-node-package

Conversation

@eizedev

@eizedev eizedev commented Nov 22, 2026

Copy link
Copy Markdown
Owner

TL;DR: pivotkit-server no longer imports pivotkit-cli. The shared file handling and REST contract live in a new internal package, pivotkit-node. Behaviour and published exports stay the same.

Why

pivotkit-server imported pivotkit-cli/files and pivotkit-cli/rest 27 times in 21 modules. A server should not depend on its command line.

Where the shared code goes

A new small workspace package, pivotkit-node, which pivotkit-cli and pivotkit-server both depend on. The CLI stays a leaf. This is the common npm-workspaces answer when two published packages share code without a bundler. The alternatives do not fit:

  • pivotkit-core: browser-safe, fflate only. The code needs node:fs, node:net, pivotkit-xlsx and pivotkit-report (a cycle).
  • pivotkit-report: runs in the browser and has no xlsx dependency.
  • pivotkit-server: the CLI would then depend on the server.

What changes

  • safe-files.js, files.js (readTable) and rest-contract.js move to packages/pivotkit-node unchanged.
  • CliError, asCliError, printable and shortName move from the CLI's errors.js. RemoteError stays in the CLI.
  • asCliError's mapping of pivotkit-core errors is its own small function. The logic is the same, and the moved test covers it.
  • pivotkit-cli/files and pivotkit-cli/rest re-export the same names and bindings, so instanceof CliError holds across both. A test checks the identity.
  • ESLint refuses an import of pivotkit-cli in pivotkit-server, and of the CLI or the services in pivotkit-node.
  • The file handling's tests (unit and junction) move with the code. CI runs them on Windows and macOS too.
  • pivotkit-server keeps pivotkit-cli as a dependency only for pivotkit-server cli, which loads it with import().

Release

pivotkit-node is a new npm name. It needs the one-time setup in RELEASING.md before pivotkit-cli or pivotkit-server is released. A minor of it moves cli and server in the same round. RELEASING.md says both.

Growth

before after
complexity offenders 106 105
function length offenders 48 48
unused exports 223 222
docs total lines 25817 25820

Gone: asCliError complexity (27) and the unused export PRINT_LENGTH. The baseline is lowered with --update.

Checks

  • npm run lint, npm run types (with the new consumer type test), npm test in every workspace and tests/*.test.js, npm run growth and pack:check for pivotkit-node and pivotkit-cli all pass.
  • The exports of every cli, server, mcp and report entry are identical before and after (Object.keys snapshot).
  • Browser specs that spawn the CLI (sheet-views, source-data) pass in chromium.

Places checked: README (packages, changelogs), AGENTS.md, the package AGENTS.md files, RELEASING.md, SECURITY.md, docs (versioning, features, faq, embed, cli, rest, mcp), the release, docs and CI workflows, the Dockerfile, eslint config, changelogs of cli, server and node.

🤖 Generated with Claude Code

eizedev and others added 2 commits November 22, 2026 19:38
…node

pivotkit-server imported pivotkit-cli/files and pivotkit-cli/rest in 21
modules, so the server depended on its own command line. The shared code
moves into a new internal package, pivotkit-node, which both depend on.
pivotkit-cli/files and pivotkit-cli/rest re-export the same names, so the
published entries stay as they are.

- safe-files.js, files.js (readTable) and rest-contract.js move as they
  are; CliError, asCliError, printable and shortName move from errors.js,
  RemoteError stays in the CLI.
- asCliError's kind mapping for pivotkit-core errors is its own function,
  so the moved function is under the growth limit.
- The file handling's unit and junction tests move with it; CI runs
  pivotkit-node's tests on Windows and macOS too.
- Package lists (workspaces, pack check, release and docs workflows,
  Dockerfile, RELEASING, README, SECURITY, docs) name the new package.

pivotkit-server keeps pivotkit-cli as a dependency only for the
`pivotkit-server cli` command.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… named

- ESLint refuses an import of pivotkit-cli in pivotkit-server, and of
  pivotkit-cli, pivotkit-server or pivotkit-mcp in pivotkit-node.
- RELEASING counts nine packages and says pivotkit-node needs its
  one-time setup first and moves with cli and server on a minor.
- cli.md names the REST service and the MCP server as the users of the
  file handling; the package counts name the public packages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eizedev
eizedev merged commit d4bd866 into main Nov 22, 2026
25 checks passed
@eizedev
eizedev deleted the refactor/shared-node-package branch November 22, 2026 20:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant